如何避免 Kylin 启动、Cube、查询常见问题？|社区近期常见问题汇总

本文整理与分析了 2019 年 4 月至 10 月期间 Apache Kylin 社区用户讨论的常见问题，涉及 Kylin 启动、权限管理、Cube 、查询、数据源与元数据、配置项、REST API等方面，根据不同的使用情景尽力给出了解决方案或可以尝试的大致方向，希望能够帮助社区小伙伴更高效地使用 Kylin。

虽然很多问题的表面报错看起来是一样的，原因却不尽相同，需要具体问题具体分析，如果文中所提供的方法不能解决你的问题，欢迎携报错日志以及各组件版本、特殊配置到 Kylin 邮件列表讨论。

文末留言讨论

当您在使用 Kylin 的过程中遇到问题时，都是如何解决的？还有哪些问题一直没得到解答？欢迎拉到文末留言，来和我们讨论哦～

如何避免高频问题

与 Kylin 启动、Cube 以及查询相关的问题出现频率较高，这三个部分也是 Kylin 的核心模块。下面是针对高频问题模块进行的分析：

1. Kylin 启动-从二进制包启动

Kylin 运行在 Hadoop 集群之上，环境安装过程比较复杂，导致很多用户在第一步启动 Kylin 时会遇到错误，多半是环境中某个组件不能正常使用或者版本适配问题所导致的，需要根据报错信息定位。

如何避免此类问题：Kylin 社区在发布新版本之前都会在主流的 HDP 和 CDH 版本进行环境测试，所以推荐用户在主流 HDP 或 CDH 集群之上部署 Kylin。初学者建议先使用docker镜像对Kylin进行学习，参考http://kylin.apache.org/docs/install/kylin_docker.html。对大数据相关组件运行原理有一定了解能够帮助分析错误。

2. Cube相关-Cube构建

此部分问题大多是由于用户资源不够充足导致的，或者是用户使用的 kylin 版本太低。

如何避免此类问题：建议首先使用kylin提供的sample cube进行构建，保证sample cube的构建没有问题，kylin环境基本上就没有问题。为kylin所在集群提供足够的资源并使用正在维护的稳定版本，能够解决大多数构建问题。

3. 查询相关：

如何避免此类问题：建议初学者参考官网文档：http://kylin.apache.org/cn/docs/tutorial/sql_reference.html，此页面提供了 Kylin 支持的函数和语法。

常见问题汇总与解答

本文将近期的常见问题分为 8 个部分，共 16 类，并且按照 Kylin 使用的常规顺序进行排序，方便用户根据自己的问题进行查找。

模块	类别
1. Kylin启动	1.1 从二进制包启动
1.2 源码编译
2. 权限管理	2.1 用户权限管理
3. Cube相关	3.1 Cube设计与优化
3.2 Cube构建
3.3 SPARK构建
3.4 中间表
3.5 历史数据更新
4. 查询相关	4.1 SQL函数支持
4.2 BI工具
4.3 性能评价
5. 数据源与元数据	5.1 NRT/KAFKA数据源
5.2 元数据
6. 配置项	6.1 配置项
7. REST API	7.1 REST API
8. 其他	8.1 其他

1. Kylin 启动

1.1 从二进制包启动

1.1.1 Kylin启动报错 java.lang.NoSuchMethodError: org/apache/tomcat/JarScanner.scan(Lorg/apache/tomcat/JarScanType;Ljavax/servlet/ServletContext

这应该是由于tomcat-api.jar和jetty-runner运行库差异导致的。你可以在$KYLIN_HOME/bin/find-hive-dependency.sh文件中，找到“hive_lib=`find -L ${hive_lib_dir} -name '*.jar' ! -name '*druid*' ! -name '*slf4j*' ! -name '*avatica*' ! -name '*calcite*' !...add: ! -name '*jetty-runner*'”，将jetty-runner从这里删除，然后再次尝试看问题是否还存在。

1.1.2 启动 kylin 时报错 Failed to find metadata store by url: kylin_metadata@hbase

如果是首次启动遇见此类错误，请检查HBase是否可以正常连接，并测试当前shell用户是否有权限创建Hbase Table，如果以上步骤没有问题，请检查当前kylin是否支持所使用的Hbase版本，请参考http://kylin.apache.org/cn/docs/install/index.html 检查版本适配情况。

如果是在重装集群后kylin报此类错误，可能是由于之前遗留的元数据冲突造成，可以将元数据备份后将原来存储元数据的hbase表删除，然后重新启动kylin尝试，如果没有提前对元数据进行备份，原有的model和cube将无法恢复，请谨慎操作。

元数据的备份和恢复可参考：http://kylin.apache.org/cn/docs/howto/howto_backup_metadata.html。

1.1.3 Check-env.sh成功，但是启动失败并报错：java.lang.NoSuchMethodError: org.joda.time.format.DateTimeFormatter.withZoneUTC()Lorg/joda/time/format/DateTimeFormatter;）

在 EMR5.8+ 环境下可能会出现此类错误，这是一个已经解决的 issue，并且已经在 Kylin 2.3.0 修复。具体细节请参考:https://issues.apache.org/jira/browse/KYLIN-3129。

1.1.4 执行 kylin.sh start 启动 kylin 时，在检查环境阶段报错

（1）首先检查产生报错的环境是否能够正常运行，比如Hive环境检查出错时执行‘ hive -e “select 1” ’，如果可以正常返回结果，那么可以接着单独执行对应的环境检查脚本find-hive-dependency.sh来获取更详细的日志信息，根据日志信息继续进行错误排查。

（2）如果所有环境都可以正常运行，那么检查bin/find-hadoop-conf-dir.sh脚本内容，该脚本中会尝试定位到你的HADOOP_CONF_DIR，此目录中应该包含core-site.xml, yarn-site.xml文件，如果kylin没有自动找到这个目录，你可以在配置文件conf/kylin.properties中手动配置"kylin.env.hadoop-conf-dir"。

1.2 源码编译

1.2.1 编译源码时出现错误：Could not transfer artifact org.apache.kylin:kylin-core-common:pom:2.6.4-SNAPSHOT from /tokyligence (http://repository.kyligence.io:8081/repository/maven-public/)

Kylin的maven仓库端口已经在80上启用，同时旧的端口8081也在使用。如果使用8081端口报错，请在pom.xml文件中更改8081为80后重新尝试。

1.2.2 编译源码时出错：Failed to execute goal net.alchim31.maven:scala-maven-plugin:4.1.0:compile (scala-compile-first) on project kylin-engine-spark: Execution scala-compile-first of goal net.alchim31.maven:scala-maven-plugin:4.1.0:compile failed

请在项目根目录下找到scala-maven-plugin，取消其版本注释，如下图：

2. 用户权限管理

2.1 用户权限管理

2.1.1 如何创建用户和用户组？

在kylin 3.0.0 beta中已经增加了创建用户和用户组的模块，可以在kylin的System页面对用户和用户组进行管理。详情请参考https://issues.apache.org/jira/browse/KYLIN-4122。

3. Cube 相关

3.1 Cube设计与优化

3.1.1 如何为cuboid设置黑名单？

目前kylin只允许用户设置白名单而没有黑名单。你可以利用聚合组来避免你不想要的cuboid出现，比如，如果存在A、B、C、D四个维度，你不想要C+D的cuboid，那么你可以将它们分为ABC和ABD两个聚合组，这样kylin就不会计算C+D的cuboid。

3.1.2 高基数维度在Rowkey中应该放在什么位置？

如果在SQL查询中，高基数维度只用于group by，而不用于where条件，应该将它们放在其他用于过滤条件的维度之后。

3.1.3 为什么Cuboid数量和预期不一致？

从kylin 2.5.0开始，kylin会默认启用cube planner功能，这个功能会自动优化当前cube，减少cuboid数量。更多关于cube planner的信息请参考http://kylin.apache.org/docs/tutorial/use_cube_planner.html。

3.2 Cube构建

3.2.1 为什么cube构建很慢或者卡在某个步骤（一般是第一步或者构建字典步骤），日志没有报错？应该如何加速cube构建？

出现这种现象一般是资源不足导致的。请检查kylin所在集群的YARN资源使用情况，可以使用“yarn application -list”来检查JOB的状态，如果YARN没有足够的资源，JOB会一直停留在SUBMITTED或者ACCEPTED状态。

如果无法增加集群资源，可以考虑对cube做剪枝优化，参考文档：

http://kylin.apache.org/cn/docs/howto/howto_optimize_cubes.html

http://kylin.apache.org/cn/docs/howto/howto_optimize_build.html

如果某个cube中含有较多的count(distinct)和topN度量，也会对构建速度产生一定的影响，可根据实际需求灵活调整。

3.2.2 使用 kylin 构建 cube 第三步报错java.lang.NullPointerException at org.apache.kylin.cube.model.CubeJoinedFlatTableDesc.getColumnIndex

如果使用kylin提供的样例数据构建cube没有报错，而在使用自己的数据进行构建时出现此类错误，可能是由于所使用的kylin版本过低，请更换更新的稳定版本进行尝试，建议使用正在维护的稳定版本。Kylin的每一次版本发布都会修复一些已知问题，可以查看官网下载页面http://kylin.apache.org/cn/download/中的发布说明来选择使用版本。

3.2.3 为什么无法并行构建同一个cube的不同segment？

这种情况应该只会在开启了cube planner（默认开启）并且cube中没有处于ready状态的segment时发生。这是为了避免cube的Build任务和优化任务同时进行而设计的，因为两个任务都可能会改变cuboid的设置从而导致一些问题。

3.2.4 Build操作和Refresh操作有什么不同？

Refresh操作是以segment为单位的，用户只能指定刷新某个segment，后台收到刷新请求会首先检查指定segment是否存在；而Build操作则不会做此检查，并且可以指定分区范围构建。如果你实际需要的操作是刷新某个segment而不是构建，建议使用Refresh，这样会更安全。

3.2.5 在 Cube 构建的过程中，为什么会有时出现job killed by admin的现象？

当map任务所使用的内存远大于任务允许从YARN获取的内存时，job

Container就会被kill。Kylin 支持在项目和 Cube 级别重写 kylin_job_conf.xml 和 kylin_job_conf_inmem.xml 文件中的参数，用户可以通过设置kylin.engine.mr.config-override.mapreduce.map.java.opts和kylin.engine.mr.config-override.mapreduce.map.memory.mb两个参数的值来从YARN获取更多内存。

3.2.6 Cube构建时出现java.lang.OutOfMemoryError: Java heap space的错误

在构建字典或者合并字典步骤可能会出现这种错误。这一般是由于构建字典的维度基数过高导致的，通常情况下string类型的字典构建只支持500万以下的维度基数，如果维度基数很高，字典的大小就会非常可观，从而不适合加载到内存中。在维度列为int类型的情况下，如果你想要构建更大基数的维度字典，请使用“int”编码方式进行字典构建。

3.2.7 构建cube时出错：java.io.IOException: Failed to read big resource /dict/KYLIN_VIEW.xxxxxxxxxxxxxxxx/COUNTRY/66292068-e8eb-975a-3e44-b56c933c14cc.dict

（1）首先请使用“$KYLIN_HOME/bin/metastore.sh fetch /dict”将字典文件备份到本地，然后检查报错的字典文件是否存在。

（2）查看logs/kylin.log中的详细报错信息并确认当前用户拥有hdfs目录权限。

（3）清理相关存储后尝试重新构建出错的cube。

（4）对出错cube所使用的hive表建立hive视图并重新命名，从该hive视图重新建立一个新的同样的cube。

这个问题的出现可能与https://issues.apache.org/jira/browse/KYLIN-4153有关，在kylin 2.6.4修复。

3.2.8 构建cube在第三步出现错误java.lang.IllegalStateException

如果存在多个Kylin server，出现这个问题的可能原因是某个Job server对元数据进行了更新，但是没有及时广播到其他的Job Server，这个问题已经在kylin 2.6.0解决，详情请查看https://issues.apache.org/jira/browse/KYLIN-3740。在kylin 2.6.0以下版本遇到这个问题时，可以尝试重新加载元数据并继续执行失败的作业。

3.3 SPARK构建

3.3.1 使用spark构建时在Convert Cuboid Data to HFile步骤出现java.lang.NoClassDefFoundError:Lorg/apache/hadoop/hbase/metrics/MetricRegistry;报错

这可能是由于没有正确找到JAR包路径导致的。你可以尝试使用如下命令查找含有该类的jar包：

find /opt -name "*.jar" | xargs grep

org.apache.hadoop.hbase.metrics.MetricRegistry

然后将其复制到$SPARK_HOME/jars/后重启kylin，重跑报错任务。

3.3.2 使用spark构建出现报错:java.lang.RuntimeException: Could not create  interface org.apache.hadoop.hbase.regionserver.MetricsRegionServerSourceFactory

这是一个已知的issue，可能会在某些版本的hadoop出现。复制你环境中的hbase-hadoop2-compat-*.jar和hbase-hadoop-compat-*.jar到$SPARK_HOME/jars/后重启kylin，然后重跑产生报错的任务查看问题是否解决。

3.3.3 使用spark引擎构建cube报错

（1）   首先查看logs/kylin.log中的错误日志来获取详细信息。

（2）根据文档：

http://kylin.apache.org/docs/tutorial/cube_spark.html检查kylin.properties配置是否正确。

3.4 中间表

3.4.1 如何设置随机分发中间表？

Kylin在打平表之后有一个“重新分发中间表”步骤来重新分发数据，这是为了避免文件分布不平衡导致之后的MR任务出现数据倾斜的问题。在重新分发中间表的过程中，首先kylin会计算出中间表的行数，然后根据行数的大小计算出重新分发数据所需要的文件数。默认情况下，kylin为每一百万行数据分配一个文件。在kylin 2.4.0之前的版本中，如果cube没有指定分区列，那么Kylin会使用“DISTRIBUTE BY RAND()”请求Hive随机分发数据，但是https://issues.apache.org/jira/browse/KYLIN-3388发现随机分发有时会导致数据不一致，所以在发布kylin2.4.0时修复了这个问题，默认会根据rowkey的前三列进行分发。如果你的数据不存在数据倾斜问题，可以将参数"kylin.source.hive.redistribute-flat-table"设置为false来禁用重新分发步骤。

3.4.2 构建完成后kylin没有将中间表删除

当从hive视图构建cube时，可能会存在构建完成后根据维度表生成的中间表没有被删除的现象，这个问题在kylin 3.0.0 beta以及kylin2.6.4中被修复，参见https://issues.apache.org/jira/browse/KYLIN-4121。

3.5 历史数据更新

3.5.1 怎样定时自动刷新kylin中的cube？

Kylin并没有提供定时器或者调度函数来定时刷新cube。可以从外部定时自动触发构建，比如linux的cron、airflow以及REST API等。

3.5.2 如何配置cube和增量更新方式，能够最高效实现事实表历史数据的指标更新？

由于Kylin基于预计算，所以是不支持数据回填（write-back）的。在Kylin中高效更新历史数据的准则就是尽量不要重刷没有变化的数据，变化的数据则总是要重新刷新的。

Kylin以segment作为刷新单位，如果历史数据经常变化的字段之间不需要关联计算，可以将它们拆分在不同的cube中，分别作为分区列，刷新数据时根据分区列进行刷新。但是这样做可能存在不同cube之间数据不一致的风险。

另外，一般来说，数据的更新具备冷热属性，即热数据经常更新，冷数据不更新，因此可以针对冷热数据设计不同规模的segment，减少刷新时的复杂度。

3.5.3 维度表更新之后如何高效更新相关cube和model？

你可以在cube列表的action中点击Lookup Refresh来单独刷新维度表快照。

3.5.4 设计完 model 和 cube 后修改使用到的数据源表的表结构，比如增加字段或修改字段，无法 reload table

如果更改数据源的字段名，则需要删除字段中使用的模型和多维数据集以重新加载表，否则将发生冲突。通常，在数据表已经应用于model和cube之后，我们不建议对表结构进行任何更改，尤其是已经使用的字段。

4. 查询相关

4.1 SQL函数支持

4.1.1 Kylin中有求交集的函数吗？比如计算留存率？

Kylin中提供intersect_count函数对数据做留存分析、漏斗分析等，函数用法请参考https://kylin.apache.org/blog/2016/11/28/intersect-count/，以及使用intersect_count实现精准留存分析的案例https://kyligence.io/zh/blog/kylin-precise-retention-analysis/。

4.1.2 在查询语句中可以使用GROUP BY <constant>吗？

Kylin支持包含类似“GROUP BY 1，2，3”的查询语句，其中的常数代表查询列的索引。详细内容可参考https://issues.apache.org/jira/browse/KYLIN-3480。

4.1.3 kylin的sum函数该如何用于varchar类型的字段？

类似于SUM的代数函数只能用于数值类型的字段。如果想在kylin中计算非数值类型字段，可以为该hive表定义一个hive视图，在视图表中将该字段转换为数值类型，再使用hive视图表建立cube。

4.1.4 Kylin支持列与列之间的乘法吗？

Kylin中没有乘法度量，所以不支持在列与列之间做乘法。如果你想对两列相乘之后的结果做聚合运算（比如SUM）的话，可以在hive表中定义一个列Z=X*Y，然后再在kylin中定义SUM(Z)作为度量。如果你不想在hive表中添加列，可以将该列定义在hive视图中，然后用hive视图作为cube的事实表进行构建。

4.2 BI 工具

4.2.1 Kylin如何使用JDBC连接Tableau？

已经发布的Kylin 3.0.0 alpha2修复了之前使用JDBC连接tableau存在的问题，具体使用方法请参考文章https://mp.weixin.qq.com/s/Oe-bkR3Zj9ugBASNVVfKRA。

4.2.2 如何使用PowerBI连接kylin？

请查看文档http://kylin.apache.org/docs/tutorial/powerbi.html。

4.3 性能评价

4.3.1 Kylin的查询性能如何评价？

请参考：https://github.com/Kyligence/ssb-kylin &  https://github.com/Kyligence/kylin-tpch，这里详细记录了指定配置下kylin查询的响应时间和基准测试结果。

5. 数据源与元数据

5.1 NRT/KAFKA数据源

5.1.1 在HDP3.0环境下，构建NRT Cube出现错误：Missing required configuration "partition.assignment.strategy"

这是由于JAR包冲突导致的。经过测试，可以参考https://issues.apache.org/jira/browse/KYLIN-3970 来解决这个问题。

5.1.2 从kafka数据源构建cube，生成的"Data_Start"和 "Hour_Start"的时区不正确

这是关于时区问题的一个bug，已经在kylin 2.6.2修复。可参考https://issues.apache.org/jira/browse/KYLIN-3788。

5.2 元数据

5.2.1 怎样将设计好的kylin项目便捷的发布到生产环境？

如果你在测试环境设计好了modle和cube，可以通过备份元数据的方式将其快速发布应用到生产环境。在kylin中，table、project、model、cube等信息都保存在元数据中，并且提供脚本对元数据进行备份和恢复，请参考文档http://kylin.apache.org/docs/howto/howto_backup_metadata.html。

5.2.2 Kylin支持parquet存储吗？

Kylin on parquet目前正在开发中。

6. 配置项

6.1 配置项

6.1.1 如何修改邮件端口并使其生效？

首先修改配置文件kylin.properties中的参数‘kylin.job.notification-mail-port’为你的邮件端口，并重启kylin使配置项生效。在此之前，请确保您有权使用该SMTP。

如果新的端口仍然不生效的话，您可以更改配置项‘kylin.job.notification-mail-enable-starttls’为false后重新尝试。因为根据MailService.java中的源码，当‘kylin.job.notification-mail-enable-starttls’为true时，会将‘kylin.job.notification-mail-port’的值设置为SSL SMTP端口，而不是SMTP端口。

6.1.2 如何修改Web页面显示的时区？

可以通过在配置文件kylin.properties中配置‘kylin.web.timezone’来指定web页面显示的时区。

7. REST API

7.1 REST API

7.1.1 如何使用Rest API对kylin进行操作？

请参考文档：http://kylin.apache.org/cn/docs/howto/howto_use_restapi.html，文档中列出了kylin中大部分主要的REST API及其用法，如果返回错误请仔细检查URL是否正确以及web端返回的异常状态码。当按照文档中的用法无法得到正确结果或者文档中没有提供你想使用的REST API的用法时，请通过邮件列表反馈问题，我们会及时处理。

8. 其他

8.1 其他

8.1.1 kylin当前支持的各组件版本是什么？

请查看文档http://kylin.apache.org/docs/install/index.html。

8.1.2 关于Kylin on druid

Kylin没有提供Kylin on druid的包，如果想要使用需要从kylin-on-druid分支自己打包。首先从kylin仓库克隆源码到本地然后切换到kylin-on-druid分支，然后参考http://kylin.apache.org/development/howto_package.html编译出对应的二进制包。我们曾经在CDH5.15环境下使用druid0.11版本验证过过功能可用。

8.1.3 查询时报“Table not found”的错误

请检查Table对应cube的状态是否为Ready。

8.1.4 如何查看在kylin执行过的query list及其状态？

可以通过查看logs/kylin.log获取查询列表，日志中会详细记录每一条历史查询的状态。

8.1.5 为什么创建system cube后发现生成的Hive表中没有数据？生成Hive表的逻辑是什么？

可以阅读org.apache.kylin.tool.metrics.systemcube.SCCreator类的源码学习其中的逻辑，创建system cube中hive表的create_hive_tables_for_system_cubes.sql是由该类的generateAllSQL()方法生成的。

当生成的Hive表中没有数据时，可以检查create_hive_tables_for_system_cubes.sql的内容是否为hive表插入了数据。

8.1.6 如何使用https协议登录登录kylin？

可以使用如下两种方式进行配置。

（1）由于kylin依赖apache tomcat 7进行web访问，所以需要为tomcat配置SSL证书。配置方法可以参考https://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html。kylin安装包中的Tomcat文件夹位于$KYLIN_HOME/tomcat，配置文件在$KYLIN_HOME/tomcat/conf。

（2）使用Nginx对tomcat web server做反向代理，然后为Nginx配置SSL证书。

参加社区讨论

如果您在使用 Kylin 的过程中遇到疑问或问题，请发送包含日志以及各组件版本、特殊配置等内容的邮件至 Apache Kylin user 或 dev 邮件列表讨论：

[e-mail], [e-mail]

注意：该邮件列表需要订阅才能使用。如未订阅该邮件列表，请先发送邮件至 [e-mail] 或 [e-mail]，并回复确认完成订阅。

文末留言讨论

当您在使用 Kylin 的过程中遇到问题时，都是如何解决的？还有哪些问题一直没得到解答？欢迎拉到文末留言，来和我们讨论哦～

往期案例与实践

"Apache and Apache Kylin are either registered trademarks or trademarks of The Apache Software Foundation in the US and/or other countries. No endorsement by The Apache Software Foundation is implied by the use of these marks."